home *** CD-ROM | disk | FTP | other *** search
/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / man / lib / tk / DoOneEvent.man < prev    next >
Encoding:
Text File  |  1992-08-24  |  8.3 KB  |  308 lines
  1. '\"
  2. '\" Copyright 1990-1992 Regents of the University of California
  3. '\" Permission to use, copy, modify, and distribute this
  4. '\" documentation for any purpose and without fee is hereby
  5. '\" granted, provided that this notice appears in all copies.
  6. '\" The University of California makes no representations about
  7. '\" the suitability of this material for any purpose.  It is
  8. '\" provided "as is" without express or implied warranty.
  9. '\" 
  10. '\" $Header: /user6/ouster/wish/man/RCS/DoOneEvent.man,v 1.6 92/05/01 16:21:32 ouster Exp $ SPRITE (Berkeley)
  11. '\" 
  12. .\" The definitions below are for supplemental macros used in Sprite
  13. .\" manual entries.
  14. .\"
  15. .\" .HS name section [date [version]]
  16. .\"    Replacement for .TH in other man pages.  See below for valid
  17. .\"    section names.
  18. .\"
  19. .\" .AP type name in/out [indent]
  20. .\"    Start paragraph describing an argument to a library procedure.
  21. .\"    type is type of argument (int, etc.), in/out is either "in", "out",
  22. .\"    or "in/out" to describe whether procedure reads or modifies arg,
  23. .\"    and indent is equivalent to second arg of .IP (shouldn't ever be
  24. .\"    needed;  use .AS below instead)
  25. .\"
  26. .\" .AS [type [name]]
  27. .\"    Give maximum sizes of arguments for setting tab stops.  Type and
  28. .\"    name are examples of largest possible arguments that will be passed
  29. .\"    to .AP later.  If args are omitted, default tab stops are used.
  30. .\"
  31. .\" .BS
  32. .\"    Start box enclosure.  From here until next .BE, everything will be
  33. .\"    enclosed in one large box.
  34. .\"
  35. .\" .BE
  36. .\"    End of box enclosure.
  37. .\"
  38. .\" .VS
  39. .\"    Begin vertical sidebar, for use in marking newly-changed parts
  40. .\"    of man pages.
  41. .\"
  42. .\" .VE
  43. .\"    End of vertical sidebar.
  44. .\"
  45. .\" .DS
  46. .\"    Begin an indented unfilled display.
  47. .\"
  48. .\" .DE
  49. .\"    End of indented unfilled display.
  50. .\"
  51. '\"    # Heading for Sprite man pages
  52. .de HS
  53. .if '\\$2'cmds'       .TH \\$1 1 \\$3 \\$4
  54. .if '\\$2'lib'        .TH \\$1 3 \\$3 \\$4
  55. .if '\\$2'tcl'        .TH \\$1 3 \\$3 \\$4
  56. .if '\\$2'tk'         .TH \\$1 3 \\$3 \\$4
  57. .if t .wh -1.3i ^B
  58. .nr ^l \\n(.l
  59. .ad b
  60. ..
  61. '\"    # Start an argument description
  62. .de AP
  63. .ie !"\\$4"" .TP \\$4
  64. .el \{\
  65. .   ie !"\\$2"" .TP \\n()Cu
  66. .   el          .TP 15
  67. .\}
  68. .ie !"\\$3"" \{\
  69. .ta \\n()Au \\n()Bu
  70. \&\\$1    \\fI\\$2\\fP    (\\$3)
  71. .\".b
  72. .\}
  73. .el \{\
  74. .br
  75. .ie !"\\$2"" \{\
  76. \&\\$1    \\fI\\$2\\fP
  77. .\}
  78. .el \{\
  79. \&\\fI\\$1\\fP
  80. .\}
  81. .\}
  82. ..
  83. '\"    # define tabbing values for .AP
  84. .de AS
  85. .nr )A 10n
  86. .if !"\\$1"" .nr )A \\w'\\$1'u+3n
  87. .nr )B \\n()Au+15n
  88. .\"
  89. .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
  90. .nr )C \\n()Bu+\\w'(in/out)'u+2n
  91. ..
  92. '\"    # BS - start boxed text
  93. '\"    # ^y = starting y location
  94. '\"    # ^b = 1
  95. .de BS
  96. .br
  97. .mk ^y
  98. .nr ^b 1u
  99. .if n .nf
  100. .if n .ti 0
  101. .if n \l'\\n(.lu\(ul'
  102. .if n .fi
  103. ..
  104. '\"    # BE - end boxed text (draw box now)
  105. .de BE
  106. .nf
  107. .ti 0
  108. .mk ^t
  109. .ie n \l'\\n(^lu\(ul'
  110. .el \{\
  111. .\"    Draw four-sided box normally, but don't draw top of
  112. .\"    box if the box started on an earlier page.
  113. .ie !\\n(^b-1 \{\
  114. \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
  115. .\}
  116. .el \}\
  117. \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
  118. .\}
  119. .\}
  120. .fi
  121. .br
  122. .nr ^b 0
  123. ..
  124. '\"    # VS - start vertical sidebar
  125. '\"    # ^Y = starting y location
  126. '\"    # ^v = 1 (for troff;  for nroff this doesn't matter)
  127. .de VS
  128. .mk ^Y
  129. .ie n 'mc \s12\(br\s0
  130. .el .nr ^v 1u
  131. ..
  132. '\"    # VE - end of vertical sidebar
  133. .de VE
  134. .ie n 'mc
  135. .el \{\
  136. .ev 2
  137. .nf
  138. .ti 0
  139. .mk ^t
  140. \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
  141. .sp -1
  142. .fi
  143. .ev
  144. .\}
  145. .nr ^v 0
  146. ..
  147. '\"    # Special macro to handle page bottom:  finish off current
  148. '\"    # box/sidebar if in box/sidebar mode, then invoked standard
  149. '\"    # page bottom macro.
  150. .de ^B
  151. .ev 2
  152. 'ti 0
  153. 'nf
  154. .mk ^t
  155. .if \\n(^b \{\
  156. .\"    Draw three-sided box if this is the box's first page,
  157. .\"    draw two sides but no top otherwise.
  158. .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
  159. .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
  160. .\}
  161. .if \\n(^v \{\
  162. .nr ^x \\n(^tu+1v-\\n(^Yu
  163. \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
  164. .\}
  165. .bp
  166. 'fi
  167. .ev
  168. .if \\n(^b \{\
  169. .mk ^y
  170. .nr ^b 2
  171. .\}
  172. .if \\n(^v \{\
  173. .mk ^Y
  174. .\}
  175. ..
  176. '\"    # DS - begin display
  177. .de DS
  178. .RS
  179. .nf
  180. .sp
  181. ..
  182. '\"    # DE - end display
  183. .de DE
  184. .fi
  185. .RE
  186. .sp .5
  187. ..
  188. .HS Tk_DoOneEvent tk
  189. .BS
  190. .SH NAME
  191. Tk_DoOneEvent, Tk_MainLoop, Tk_HandleEvent \- wait for events and
  192. invoke event handlers
  193. .SH SYNOPSIS
  194. .nf
  195. \fB#include <tk.h>\fR
  196. .sp
  197. int
  198. .VS
  199. \fBTk_DoOneEvent\fR(\fIflags\fR)
  200. .VE
  201. .sp
  202. \fBTk_MainLoop\fR()
  203. .sp
  204. \fBTk_HandleEvent\fR(\fIeventPtr\fR)
  205. .SH ARGUMENTS
  206. .AS XEvent *eventPtr
  207. .AP int flags in
  208. .VS
  209. This parameter is normally zero.  It may be an OR-ed combination
  210. of any of the following flag bits:  TK_X_EVENTS, TK_FILE_EVENTS,
  211. TK_TIMER_EVENTS, TK_IDLE_EVENTS, TK_ALL_EVENTS, or TK_DONT_WAIT.
  212. .VE
  213. .AP XEvent *eventPtr in
  214. Pointer to X event to dispatch to relevant handler(s).
  215. .BE
  216.  
  217. .SH DESCRIPTION
  218. .PP
  219. These three procedures are responsible for waiting for events
  220. and dispatching to event handlers created with the procedures
  221. \fBTk_CreateEventHandler\fR, \fBTk_CreateFileHandler\fR,
  222. \fBTk_CreateTimerHandler\fR, and \fBTk_DoWhenIdle\fR.
  223. \fBTk_DoOneEvent\fR is the key procedure.  It waits for a single
  224. event of any sort to occur, invokes the handler(s) for that
  225. event, and then returns.  \fBTk_DoOneEvent\fR first checks
  226. for X events and file-related events;  if one is found then
  227. it calls the handler(s) for the event and returns.  If there
  228. are no X or file events pending, then \fBTk_DoOneEvent\fR
  229. checks to see if timer callbacks are ready;  if so, it
  230. makes a single callback and returns.  If no timer callbacks
  231. are ready, \fBTk_DoOneEvent\fR checks for \fBTk_DoWhenIdle\fR
  232. callbacks;  if any are found, it invokes all of them and returns.
  233. Finally, if events or work have been found found, \fBTk_DoOneEvent\fR
  234. sleeps until a timer, file, or X event occurs;  then it processes
  235. the first event found (in the order given above) and returns.
  236. The normal return value is 1 to signify that some event or callback
  237. was processed.
  238. .PP
  239. If the \fIflags\fR argument to \fBTk_DoOneEvent\fR is non-zero then
  240. .VS
  241. it restricts the kinds of events that will be processed by
  242. \fBTk_DoOneEvent\fR.
  243. \fIFlags\fR may be an OR-ed combination of any of the following bits:
  244. .TP 24
  245. \fBTK_X_EVENTS\fR \-
  246. Process X events.
  247. .TP 24
  248. \fBTK_FILE_EVENTS\fR \-
  249. Process file events.
  250. .TP 24
  251. \fBTK_TIMER_EVENTS\fR \-
  252. Process timer events.
  253. .TP 24
  254. \fBTK_IDLE_EVENTS\fR \-
  255. Process \fBTk_DoWhenIdle\fR callbacks.
  256. .TP 24
  257. \fBTK_ALL_EVENTS\fR \-
  258. Process all kinds of events:  equivalent to OR-ing together all of the
  259. above flags or specifying none of them.
  260. .TP 24
  261. \fBTK_DONT_WAIT\fR \-
  262. Don't sleep:  process only events that are ready at the time of the
  263. call.
  264. .LP
  265. If any of the flags \fBTK_X_EVENTS\fR, \fBTK_FILE_EVENTS\fR,
  266. \fBTK_TIMER_EVENTS\fR, or \fBTK_IDLE_EVENTS\fR is set, then the only
  267. events that will be considered are those for which flags are set.
  268. Setting none of these flags is equivalent to the value
  269. \fBTK_ALL_EVENTS\fR, which causes all event types to be processed.
  270. .PP
  271. The \fBTK_DONT_WAIT\fR flag causes \fBTk_DoWhenIdle\fR not to put
  272. the process to sleep:  it will check for events but if none are found
  273. then it returns immediately with a return value of 0 to indicate
  274. that no work was done.
  275. \fBTk_DoOneEvent\fR will also return 0 without doing anything if
  276. \fIflags\fR is \fBTK_IDLE_EVENTS\fR and there are no
  277. \fBTk_DoWhenIdle\fR callbacks pending.
  278. .VE
  279. .PP
  280. \fBTk_MainLoop\fR is a procedure that loops repeatedly
  281. calling \fBTk_DoOneEvent\fR.  It returns only when there
  282. are no applications left in this process (i.e. no main windows
  283. exist anymore).  Most X applications will
  284. call \fBTk_MainLoop\fR after initialization;  the main
  285. execution of the application will consist entirely of
  286. callbacks invoked by \fBTk_DoOneEvent\fR.
  287. .PP
  288. \fBTk_HandleEvent\fR is a lower-level procedure invoked
  289. by \fBTk_DoOneEvent\fR.  It makes callbacks to any event
  290. handlers (created by calls to \fBTk_CreateEventHandler\fR)
  291. that match \fIeventPtr\fR and then returns.  In some cases
  292. it may be useful for an application to read events directly
  293. from X and dispatch them by calling \fBTk_HandleEvent\fR,
  294. without going through the additional mechanism provided
  295. by \fBTk_DoOneEvent\fR.
  296. .PP
  297. These procedures may be invoked recursively.  For example,
  298. it is possible to invoke \fBTk_DoOneEvent\fR recursively
  299. from a handler called by \fBTk_DoOneEvent\fR.  This sort
  300. of operation is useful in some modal situations, such
  301. as when a
  302. notifier has been popped up and an application wishes to
  303. wait for the user to click a button in the notifier before
  304. doing anything else.
  305.  
  306. .SH KEYWORDS
  307. callback, event, handler, idle, timer
  308.